/*
 * Copyright (C) 2010-2011 Comcast Cable.  All Rights Reserved.
 */
package com.hercules.android.receiver.connection.parser;

import java.util.List;

import com.hercules.android.receiver.model.commands.XRECommand;
import com.hercules.android.receiver.model.events.XREEvent;


/**
 * <p>
 * This interface declares the methods which should be implemented by a message
 * parser. Concretely, a message parser can parse the given command as a string
 * into the XRECommand and encode the event represented by XREEvent into a
 * string. The message's format is dependent on the concrete implementation. In
 * this component, the sole implementation is JSONMessageParser, which follows
 * the JSON format of the messages given in the XRE Specification.
 * </p>
 * <p>
 * Thread safety: The implementations of this interface are not required to be
 * thread safe.
 * </p>
 *
 * @author nhzp339, wz12
 * @version 1.0
 */
public interface MessageParser {
    /**
     * <p>
     * This method parses the given commands as a string into a list of
     * XRECommands. The commands' format is dependent on the concrete
     * implementation.
     * </p>
     *
     * @param commands
     *            The string representation of the commands. Can't be null or
     *            empty. If it's a single command, it's formatted as "{command}"
     *            or "[ {command} ]", if it's multiple commands, it's formatted
     *            as "[ {command}, {command},...... {command} ]".
     * @return The XRECommands parsed from the string representation of the
     *         commands. Won't be null and won't be empty.
     * @throws IllegalArgumentException
     *             If command argument is null or empty.
     * @throws MalformedCommandException
     *             If the commands string's contents can't be recognized by the
     *             message parser.
     * @throws CommandParsingException
     *             If other error occurs during the parsing process of commands'
     *             string representations to XRECommand.
     */
    public List<XRECommand> parseCommands(String commands)
        throws CommandParsingException;

    /**
     * <p>
     * This method encodes the event represented by XREEvent into a string. The
     * string's format is dependent on the concrete implementation.
     * </p>
     *
     * @param event
     *            The event represented by XREEvent. Can't be null.
     * @return The string representation of the event. Won't be null but empty
     *         may have sense(dependent on concrete implementation)
     * @throws IllegalArgumentException
     *             If event argument is null.
     * @throws EventEncodingException
     *             If error occurs during the encoding process of XREEvent into
     *             the String representation.
     */
    public String encodeEvent(XREEvent event) throws EventEncodingException;
}
